<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Genivia - The WS-Discovery plugin</title>
<link href="genivia_tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="genivia_content.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="top">
 <div id="titlearea">
  <table height="72px" width="100%" cellspacing="0" cellpadding="0">
   <tbody>
    <tr>
     <td width="10%">&nbsp;</td>
     <td width="175px"><a href="https://www.genivia.com"><img alt="Genivia" src="GeniviaLogo2_trans_noslogan.png"/></a></td>
     <td class="tab_home"><a href="https://www.genivia.com">Home</a></td>
     <td class="tab_home"><a href="https://www.genivia.com/docs.html">Documentation</a></td>
     <td>
      <div style="float: right; font-size: 18px; font-weight: bold;">The WS-Discovery plugin</div>
      <br>
      <div style="float: right; font-size: 10px;">updated Thu Nov 19 2020 by Robert van Engelen</div>
     </td>
     <td width="10%">&nbsp;</td>
    </tr>
   </tbody>
  </table>
 </div>
<!-- Generated by Doxygen 1.8.11 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">The WS-Discovery plugin </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#wsdd_1">WS-Discovery Setup</a></li>
<li class="level1"><a href="#wsdd_2">WS-Discovery Event Handlers</a></li>
<li class="level1"><a href="#wsdd_3">WS-Discovery Event Listener</a></li>
<li class="level1"><a href="#wsdd_4">Invoking WS-Discovery Operations</a></li>
<li class="level1"><a href="#wsdd_5">Generating C++ Server Objects</a></li>
<li class="level1"><a href="#wsdd_6">Miscellaneous</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="wsdd_1"></a>
WS-Discovery Setup</h1>
<p>The material in this section relates to the WS-Discovery specification.</p>
<p>To use the wsdd library:</p>
<ol type="1">
<li>Define WS-Discovery event handlers in your code, see Section <a class="el" href="wsdd_0.html#wsdd_2">WS-Discovery Event Handlers</a>.</li>
<li>Use the wsdd API functions as described below.</li>
<li>(Re-)compile and link stdsoap2.c/pp or libgsoap, (dom.c/.cpp when needed), <a class="el" href="wsddapi_8c.html">wsddapi.c</a>, <a class="el" href="wsaapi_8c.html">wsaapi.c</a> and the soapcpp2-generated source files. Compile and link with plugin/threads.c when needed.</li>
</ol>
<p>The material in this document pertains to the WS-Discovery protocol and model and assumes that the reader is familiar with the WS-Discovery protocol, its terms and definitions, and the WS-Discovery model. This document describes the WS-Discovery interface to invoke and handle WS-Discovery events, while the higher-level logic remains application-specific. Especially the mode of operation, ad-hoc or managed with a Discovery Proxy, depends on the application deployment and WS-Discovery support requirements.</p>
<p>The following assumptions are made. A Client (C) is an endpoint that searches for Target Service(s). A Target Service (TS) is a service endpoint that makes itself available for discovery. A Discovery Proxy (DP) is an endpoint that facilitates discovery of Target Services by Clients. The interfaces defined in the wsdd library can be used to implement Client, Target Service, and Discovery Proxy operations.</p>
<p>WS-Discovery ad-hoc and managed modes are supported by the wsdd library. In an ad-hoc mode discovery messages are sent multicast and response messages are sent unicast. In a managed mode discovery messages are sent unicast to a Discovery Proxy.</p>
<dl class="section note"><dt>Note</dt><dd>The wsdl2h tool uses typemap.dat to auto-generate a gSOAP service definitions header file that imports <a class="el" href="wsdd_8h.html">wsdd.h</a> to support WS-Discovery 1.1 with WS-Addressing 2005/08. The tool imports wsdd10.h to support WS-Discovery 1.0 with WS-Addressing 2004/08. To use WS-Discovery 1.0 with WS-Addressing 2005/08, you will need to change typemap.dat to let wsdl2h import wsdd5.h (see comments in typemap.dat).</dd></dl>
<h1><a class="anchor" id="wsdd_2"></a>
WS-Discovery Event Handlers</h1>
<p>The following event handlers MUST be defined by the user to handle inbound WS-Discovery messages. The event handlers receive notifications (Hello, Bye, ProbeMatches, and ResolveMatches) or receive requests to provide data (Probe and Resolve).</p>
<p>The event handlers to define are:</p><ul>
<li><a class="el" href="wsddapi_8h.html#a24726d40e324bced15ea7c32e8e01de7">wsdd_event_Hello</a></li>
<li><a class="el" href="wsddapi_8h.html#a2741ba2ad6403207601ca2dbd9091e66">wsdd_event_Bye</a></li>
<li><a class="el" href="wsddapi_8h.html#abbabd438789cc445ee72372722e7a6f4">wsdd_event_Probe</a></li>
<li><a class="el" href="wsddapi_8h.html#acbe8ef906112805937c9f19701649ba3">wsdd_event_ProbeMatches</a></li>
<li><a class="el" href="wsddapi_8h.html#aeeb67571da9ca4a2da8730d49cae3021">wsdd_event_Resolve</a></li>
<li><a class="el" href="wsddapi_8h.html#a6fe08bbe8ab19ff2a1e0874c0a104d18">wsdd_event_ResolveMatches</a></li>
</ul>
<p>See the documentation provided with each of these functions in <a class="el" href="wsddapi_8h.html">wsddapi.h</a>.</p>
<h1><a class="anchor" id="wsdd_3"></a>
WS-Discovery Event Listener</h1>
<p>Inbound WS-Discovery multicast messages are handled via a listener on a port. The user-defined event handlers are invoked when WS-Discovery messages arrive on the port.</p>
<p>The <code>soap_wsdd_listen</code> function listens on the current port opened with <code>soap_bind</code> for WS-Discovery messages for a brief time period as specified by a timeout value in seconds (negative for micro seconds). The function allows for periodically polling the port as shown:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;<a class="code" href="wsddapi_8h.html">wsddapi.h</a>&quot;</span></div><div class="line"><span class="keywordtype">int</span> port = 8080;</div><div class="line"><span class="keyword">struct </span>soap *soap = soap_new();</div><div class="line">soap-&gt;user = (<span class="keywordtype">void</span>*)&amp;my_state;</div><div class="line"><span class="keywordflow">if</span> (!soap_valid_socket(soap_bind(soap, port, 100)))</div><div class="line">{</div><div class="line">  soap_print_fault(soap, stderr);</div><div class="line">  exit(0);</div><div class="line">}</div><div class="line"><a class="code" href="wsddapi_8h.html#aeaf4e9c91f54ffcf09534b68b5ee6778">soap_wsdd_listen</a>(soap, -1000); <span class="comment">// listen for messages for 1 ms</span></div><div class="line">...</div></div><!-- fragment --><p>WS-Discovery messages are relayed to the event handlers. The soap-&gt;user pointer can be used to point to a state object that is updated by the event handlers as per desired behavior at the Client side, the Target Service, or the Discovery Proxy implementation.</p>
<h1><a class="anchor" id="wsdd_4"></a>
Invoking WS-Discovery Operations</h1>
<p>A Client may invoke the following WS-Discovery operations:</p><ul>
<li><code>soap_wsdd_Probe</code></li>
<li><code>soap_wsdd_Resolve</code></li>
</ul>
<p>A Target Service may invoke the following WS-Discovery operations:</p>
<ul>
<li><code>soap_wsdd_Hello</code></li>
<li><code>soap_wsdd_Bye</code></li>
<li><code>soap_wsdd_ProbeMatches</code> (e.g. via <code>soap_wsdd_listen</code>)</li>
<li><code>soap_wsdd_ResolveMatches</code> (e.g. via <code>soap_wsdd_listen</code>)</li>
</ul>
<p>A Discovery Proxy can perform all operations listed above, and should use "wsdd:DiscoveryProxy" as the Type with the Hello, Bye, and ProbeMatches.</p>
<p>To send a Hello message to join a network:</p>
<div class="fragment"><div class="line"><a class="code" href="wsddapi_8h.html#a4468038ee56dc4709e1550f57dadb0c4">soap_wsdd_Hello</a>(soap,</div><div class="line">  <a class="code" href="wsddapi_8h.html#a4d8f41b14eeb3500631fd39cad15b4a7a06282f02ad809feed167d23a3cf5ac46">SOAP_WSDD_MANAGED</a>,    <span class="comment">// or SOAP_WSDD_ADHOC for ad-hoc mode</span></div><div class="line">  <span class="stringliteral">&quot;to address&quot;</span>,         <span class="comment">// &quot;http(s):&quot; URL, or &quot;soap.udp:&quot; UDP, or TCP/IP address</span></div><div class="line">  <a class="code" href="wsaapi_8h.html#ac2b81c42093fc9fcadcf86e7d801e03b">soap_wsa_rand_uuid</a>(soap), <span class="comment">// a unique message ID</span></div><div class="line">  NULL,</div><div class="line">  <span class="stringliteral">&quot;my address&quot;</span>,         <span class="comment">// where they can find me for WS-Discovery</span></div><div class="line">  <span class="stringliteral">&quot;wsdd:DiscoveryProxy&quot;</span>,<span class="comment">// Types: I&#39;m a DP</span></div><div class="line">  NULL,                 <span class="comment">// Scope</span></div><div class="line">  NULL,                 <span class="comment">// MatchBy</span></div><div class="line">  NULL,                 <span class="comment">// XAddrs</span></div><div class="line">  75965);               <span class="comment">// MDVersion</span></div></div><!-- fragment --><p>Note that <code>Types</code> above is a string with namespace-qualified names (QNames). These should be qualified as in "namespace":name or you can use a namespace prefix that is part of your namespace table (in the .nsmap). So you can use "wsdd:DiscoveryPRoxy" as a QName in Types because wsdd is a namespace prefix with a defined binding in the namespace table.</p>
<p>For UDP multicast, use</p>
<div class="fragment"><div class="line">soap.connect_flags = SO_BROADCAST;</div></div><!-- fragment --><p>and optionally set the interface and TTL settings:</p>
<div class="fragment"><div class="line">in_addr_t addr = inet_addr(<span class="stringliteral">&quot;1.2.3.4&quot;</span>);</div><div class="line">soap.ipv4_multicast_if = &amp;addr; <span class="comment">// see setsockopt IPPROTO_IP IP_MULTICAST_IF</span></div><div class="line">soap.ipv6_multicast_if = addr; <span class="comment">// multicast sin6_scope_id</span></div><div class="line">soap.ipv4_multicast_ttl = 1; <span class="comment">// see setsockopt IPPROTO_IP, IP_MULTICAST_TTL</span></div></div><!-- fragment --><p>Please refer to the socket options for <code>IPPROTO_IP</code> <code>IP_MULTICAST_IF</code> to specify the default interface for multicast datagrams to be sent from. Otherwise, the default interface set by the system administrator will be used (if any).</p>
<p>Please refer to the socket options for <code>IPPROTO_IP</code> <code>IP_MULTICAST_TTL</code> to limit the lifetime of the packet. Multicast datagrams are sent with a default value of 1, to prevent them to be forwarded beyond the local network. This parameter can be set between 1 to 255.</p>
<p>To send a Bye message to leave a network:</p>
<div class="fragment"><div class="line"><a class="code" href="wsddapi_8h.html#a5912eb51290b18adb51cfa80e8c55671">soap_wsdd_Bye</a>(soap,</div><div class="line">  <a class="code" href="wsddapi_8h.html#a4d8f41b14eeb3500631fd39cad15b4a7a06282f02ad809feed167d23a3cf5ac46">SOAP_WSDD_MANAGED</a>,    <span class="comment">// or SOAP_WSDD_ADHOC for ad-hoc mode</span></div><div class="line">  <span class="stringliteral">&quot;to address&quot;</span>,         <span class="comment">// &quot;http(s):&quot; URL, or &quot;soap.udp:&quot; UDP, or TCP/IP address</span></div><div class="line">  <a class="code" href="wsaapi_8h.html#ac2b81c42093fc9fcadcf86e7d801e03b">soap_wsa_rand_uuid</a>(soap), <span class="comment">// a unique message ID</span></div><div class="line">  NULL,</div><div class="line">  <span class="stringliteral">&quot;my address&quot;</span>,         <span class="comment">// where they can find me for WS-Discovery</span></div><div class="line">  <span class="stringliteral">&quot;wsdd:DiscoveryProxy&quot;</span>,<span class="comment">// Types: I&#39;m a DP</span></div><div class="line">  NULL,                 <span class="comment">// Scope</span></div><div class="line">  NULL,                 <span class="comment">// MatchBy</span></div><div class="line">  NULL,                 <span class="comment">// XAddrs</span></div><div class="line">  75965);               <span class="comment">// MDVersion</span></div></div><!-- fragment --><p>To send a Probe message (see WS-Discovery 1.1 Section 1.7) and then listen to ProbeMatches:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>soap soap = soap_new(); <span class="comment">// to invoke messages</span></div><div class="line"><span class="keyword">struct </span>soap serv = soap_new(); <span class="comment">// for the listener and event handlers</span></div><div class="line"></div><div class="line">soap_bind(serv, port, 100);</div><div class="line"></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *<span class="keywordtype">id</span> = <a class="code" href="wsaapi_8h.html#ac2b81c42093fc9fcadcf86e7d801e03b">soap_wsa_rand_uuid</a>(soap);</div><div class="line">serv-&gt;user = (<span class="keywordtype">void</span>*)&amp;my_state;</div><div class="line">my_state.probe_id = id;</div><div class="line"></div><div class="line"><a class="code" href="wsddapi_8h.html#a79d93ab49aba655b6b767b28d0aff6ad">soap_wsdd_Probe</a>(soap,</div><div class="line">  <a class="code" href="wsddapi_8h.html#a4d8f41b14eeb3500631fd39cad15b4a7ac6264855642c10f4a15a1c2752ba7b91">SOAP_WSDD_ADHOC</a>,      <span class="comment">// ad-hoc mode</span></div><div class="line">  <a class="code" href="wsddapi_8h.html#adcd746964993574992fa2bafa83aed5caeaede3f37955eb85c93830a96b8d0b64">SOAP_WSDD_TO_TS</a>,      <span class="comment">// to a TS</span></div><div class="line">  <span class="stringliteral">&quot;to address&quot;</span>,         <span class="comment">// address of TS</span></div><div class="line">  <span class="keywordtype">id</span>,                   <span class="comment">// message ID</span></div><div class="line">  NULL,                 <span class="comment">// ReplyTo</span></div><div class="line">  <span class="stringliteral">&quot;\&quot;http://printer.example.org/2003/imaging\&quot;:PrintBasic&quot;</span>,</div><div class="line">  <span class="stringliteral">&quot;ldap:///ou=engineering,o=examplecom,c=us&quot;</span>,</div><div class="line">  <span class="stringliteral">&quot;http://docs.oasis-open.org/ws-dd/ns/discovery/2009/01/ldap&quot;</span>);</div><div class="line"></div><div class="line"><a class="code" href="wsddapi_8h.html#aeaf4e9c91f54ffcf09534b68b5ee6778">soap_wsdd_listen</a>(serv, -1000);</div></div><!-- fragment --><p>The <code>id</code> above is the WS-Addressing message ID that will be included in the ProbeMatches RelatesTo WS-Addressing header. As an example, <code>my_state</code> is set to this <code>id</code> so that when the <code>wsdd_event_ProbeMatches</code> event handler is invoked it can find the <code>id</code> in the current state that is pointed to by <code>serv-&gt;user</code> (<code>soap-&gt;user</code> in the handler).</p>
<p>To send a Resolve message and then listen to ResolveMatches:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>soap soap = soap_new(); <span class="comment">// to invoke messages</span></div><div class="line"><span class="keyword">struct </span>soap serv = soap_new(); <span class="comment">// for the listener and event handlers</span></div><div class="line"></div><div class="line">soap_bind(serv, port, 100);</div><div class="line"></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *<span class="keywordtype">id</span> = <a class="code" href="wsaapi_8h.html#ac2b81c42093fc9fcadcf86e7d801e03b">soap_wsa_rand_uuid</a>(soap);</div><div class="line">serv-&gt;user = (<span class="keywordtype">void</span>*)&amp;my_state;</div><div class="line">my_state.resolve_id = id;</div><div class="line"></div><div class="line"><a class="code" href="wsddapi_8h.html#acfcc0ff137be16fd9706f21faaeb7b23">soap_wsdd_Resolve</a>(soap,</div><div class="line">  <a class="code" href="wsddapi_8h.html#a4d8f41b14eeb3500631fd39cad15b4a7ac6264855642c10f4a15a1c2752ba7b91">SOAP_WSDD_ADHOC</a>,      <span class="comment">// ad-hoc mode</span></div><div class="line">  <a class="code" href="wsddapi_8h.html#adcd746964993574992fa2bafa83aed5caeaede3f37955eb85c93830a96b8d0b64">SOAP_WSDD_TO_TS</a>,      <span class="comment">// to a TS</span></div><div class="line">  <span class="stringliteral">&quot;to address&quot;</span>,         <span class="comment">// address to send to</span></div><div class="line">  <span class="keywordtype">id</span>,                   <span class="comment">// message ID</span></div><div class="line">  NULL,                 <span class="comment">// ReplyTo</span></div><div class="line">  <span class="stringliteral">&quot;endpoint&quot;</span>);          <span class="comment">// EndpointReference of TS</span></div><div class="line"> </div><div class="line"><a class="code" href="wsddapi_8h.html#aeaf4e9c91f54ffcf09534b68b5ee6778">soap_wsdd_listen</a>(serv, -1000);</div></div><!-- fragment --><p>Again, the <code>id</code> and <code>my_state</code> are used to associate the asynchronously received ResolveMatches response that is handled by the <a class="el" href="wsddapi_8h.html#a6fe08bbe8ab19ff2a1e0874c0a104d18">wsdd_event_ResolveMatches</a> for the original request.</p>
<p>In managed mode with unicast messages (request-response messages), the <code>soap_wsdd_Probe</code> and <code>soap_wsdd_Resolve</code> are sufficient to invoke without setting up a listener. The event handlers are invoked when the unicast response message arrives.</p>
<p>In managed mode, the ProbeMatches and ResolveMatches are automatically sent via <code>soap_wsdd_listen</code> and the event <code>wsdd_event_Probe</code> and <code>wsdd_event_Resolve</code> handlers. These event handlers should set the matches to be returned.</p>
<p>In ad-hoc mode, ProbeMatches or ResolveMatches responses are NOT sent automatically. In ad-hoc mode the responses can be returned by adding code to the event handler or from anywhere in the main program, for example after <a class="el" href="wsddapi_8c.html#aa4adce86fc059bac2ec6fc44697edd04">soap_wsdd_listen</a>. When responses are to be returned from the event handler or from the main program, you should invoke <a class="el" href="wsddapi_8c.html#af00e0661c0105c3ba658598d5131f185">soap_wsdd_ProbeMatches</a> and <a class="el" href="wsddapi_8c.html#a923096ca493b6b2163a4b08139ed7237">soap_wsdd_ResolveMatches</a> to explicitly send unicast messages with the match(es) back to the clients. The WS-Addressing ReplyTo address can be used as the return address (when not anonymous), or by using the peer's host information that is accessible in the soap-&gt;peer and soap-&gt;peerlen members. For example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> host[1024], port[16];</div><div class="line">getnameinfo((<span class="keyword">struct</span> sockaddr*)&amp;soap-&gt;peer, soap-&gt;peerlen, host, <span class="keyword">sizeof</span>(host), port, 16, NI_DGRAM | NI_NAMEREQD | NI_NUMERICSERV);</div></div><!-- fragment --><p>The <a class="el" href="wsddapi_8c.html#af00e0661c0105c3ba658598d5131f185">soap_wsdd_ProbeMatches</a> function takes an array of <a class="el" href="structwsdd_____probe_matches_type.html">wsdd__ProbeMatchesType</a> matches to transmit. This array is created by calling functions <a class="el" href="wsddapi_8c.html#ab76b80149b6368e770386db944416670">soap_wsdd_init_ProbeMatches</a> and then <a class="el" href="wsddapi_8c.html#a76d323b0c51a45d6a1ce8ec8e45ae642">soap_wsdd_add_ProbeMatch</a> multiple times. Each call adds an element to the matches:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *endpoint, *types, *scopes, *matchby, *xaddrs;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> version;</div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> *relatesto, *to;</div><div class="line"><span class="keyword">struct </span><a class="code" href="structwsdd_____probe_matches_type.html">wsdd__ProbeMatchesType</a> matches;</div><div class="line"><a class="code" href="wsddapi_8h.html#ad3a76f8ee99b6a2d5a6e30d2d1d3badd">soap_wsdd_init_ProbeMatches</a>(soap, &amp;matches);</div><div class="line">...</div><div class="line"><span class="comment">// repeat this to add multiple matches:</span></div><div class="line">if (<a class="code" href="wsddapi_8h.html#a4f4515c5b9e25069b3a6051ffa73d288">soap_wsdd_add_ProbeMatch</a>(soap, &amp;matches, endpoint, types, scopes, matchby, xaddrs, version))</div><div class="line">  ... <span class="comment">// out of memory</span></div><div class="line">...</div><div class="line"><span class="comment">// send the ProbeMatches message</span></div><div class="line">if (<a class="code" href="wsddapi_8h.html#ac1fd8fdfb24767d214f68659bfbe4187">soap_wsdd_ProbeMatches</a>(soap, endpoint, <a class="code" href="wsaapi_8h.html#ac2b81c42093fc9fcadcf86e7d801e03b">soap_wsa_rand_uuid</a>(soap), relatesto, to, &amp;matches))</div><div class="line">  ... <span class="comment">// an error occurred</span></div></div><!-- fragment --><p>After calling <a class="el" href="wsddapi_8c.html#a76d323b0c51a45d6a1ce8ec8e45ae642">soap_wsdd_add_ProbeMatch</a> it is possible to add additional WS-Addressing header values to this matches array element. For example the WS-Addressing reference parameters channel instance:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="wsddapi_8h.html#a4f4515c5b9e25069b3a6051ffa73d288">soap_wsdd_add_ProbeMatch</a>(soap, &amp;matches, endpoint, types, scopes, matchby, xaddrs, version))</div><div class="line">  ... <span class="comment">// out of memory</span></div><div class="line"><span class="comment">// now allocate and add the WS-Addresssing reference parameters</span></div><div class="line"><span class="keyword">struct </span>wsa5__EndpointReference *ref = &amp;matches.ProbeMatch[matches.__sizeProbeMatch - 1].wsa5__EndpointReference;</div><div class="line">ref-&gt;ReferenceParameters = (<span class="keyword">struct </span><a class="code" href="structwsa5_____reference_parameters_type.html">wsa5__ReferenceParametersType</a>*)soap_malloc(soap, <span class="keyword">sizeof</span>(<span class="keyword">struct</span> <a class="code" href="structwsa5_____reference_parameters_type.html">wsa5__ReferenceParametersType</a>));</div><div class="line"><span class="keywordflow">if</span> (ref == NULL)</div><div class="line">  ... <span class="comment">// out of memory</span></div><div class="line">soap_default_wsa5__ReferenceParametersType(soap, ref-&gt;ReferenceParameters);</div><div class="line">ref-&gt;ReferenceParameters-&gt;chan__ChannelInstance = ...</div></div><!-- fragment --><p>See also the <a href="../../databinding/html/index.html">Data binding</a> documentation on allocating and initializing C/C++ data in managed memory, managed by the <code>soap</code> context.</p>
<h1><a class="anchor" id="wsdd_5"></a>
Generating C++ Server Objects</h1>
<p>The WSDD plugin is developed to support C and C++. To support C++ server objects generated with soapcpp2 option <code>-j</code> (or <code>-i</code>), run soapcpp2 again: </p><pre class="fragment">soapcpp2 -a -j -Iimport import/wsdd.h
</pre><p>You should define in your C++ code the following wrappers (use <code>this</code> instead of <code>this-&gt;soap</code> below with soapcpp2 option <code>-i</code>):</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> wsddService::Hello(<span class="keyword">struct</span> <a class="code" href="structwsdd_____hello_type.html">wsdd__HelloType</a> *hello)</div><div class="line">{</div><div class="line">  <span class="keywordflow">return</span> <a class="code" href="wsddapi_8h.html#a5ff39c1ead345380963b292a21dc9960">__wsdd__Hello</a>(this-&gt;soap, hello);</div><div class="line">}</div><div class="line"><span class="keywordtype">int</span> wsddService::Bye(<span class="keyword">struct</span> <a class="code" href="structwsdd_____bye_type.html">wsdd__ByeType</a> *bye)</div><div class="line">{</div><div class="line">  <span class="keywordflow">return</span> <a class="code" href="wsddapi_8h.html#a2ade69029974cbac3b06afb74d452964">__wsdd__Bye</a>(this-&gt;soap, bye);</div><div class="line">}</div><div class="line"><span class="keywordtype">int</span> wsddService::Probe(<span class="keyword">struct</span> <a class="code" href="structwsdd_____probe_type.html">wsdd__ProbeType</a> *probe)</div><div class="line">{</div><div class="line">  <span class="keywordflow">return</span> <a class="code" href="wsddapi_8h.html#a29c3eb211a71c1fab6c773f5b5ed1adb">__wsdd__Probe</a>(this-&gt;soap, probe);</div><div class="line">}</div><div class="line"><span class="keywordtype">int</span> wsddService::ProbeMatches(<span class="keyword">struct</span> <a class="code" href="structwsdd_____probe_matches_type.html">wsdd__ProbeMatchesType</a> *matches)</div><div class="line">{</div><div class="line">  <span class="keywordflow">return</span> <a class="code" href="wsddapi_8h.html#aaaabc1f3cc187e5724470cbfdeed1da6">__wsdd__ProbeMatches</a>(this-&gt;soap, matches);</div><div class="line">}</div><div class="line"><span class="keywordtype">int</span> wsddService::Resolve(<span class="keyword">struct</span> <a class="code" href="structwsdd_____resolve_type.html">wsdd__ResolveType</a> *resolve)</div><div class="line">{</div><div class="line">  <span class="keywordflow">return</span> <a class="code" href="wsddapi_8h.html#aa0ace89168d2e0180730cf42e0c96127">__wsdd__Resolve</a>(this-&gt;soap, resolve);</div><div class="line">}</div><div class="line"><span class="keywordtype">int</span> wsddService::ResolveMatches(<span class="keyword">struct</span> <a class="code" href="structwsdd_____resolve_matches_type.html">wsdd__ResolveMatchesType</a> *matches)</div><div class="line">{</div><div class="line">  <span class="keywordflow">return</span> <a class="code" href="wsddapi_8h.html#af1a35f73401918b02c3aa704cbb606ff">__wsdd__ResolveMatches</a>(this-&gt;soap, matches);</div><div class="line">}</div></div><!-- fragment --><p>Note that soapcpp2 option <code>-a</code> may be needed to enable automatic service dispatching of WS-Addressing services based on the SOAP Action value instead of the SOAP/XML request operation.</p>
<p>Another approach to generate the WSDD service operations is to run soapcpp2 separately on <a class="el" href="wsdd_8h.html">wsdd.h</a> (or wsdd5.h or wsdd10.h for WS-Discovery 1.0) by: </p><pre class="fragment">soapcpp2 -a -L -pwsdd -Iimport import/wsdd.h
</pre><p>Now with this approach you must chain the service operations at the server side as follows:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (soap_begin_serve(service.soap) == SOAP_OK)</div><div class="line">  <span class="keywordflow">if</span> (service.dispatch() == SOAP_NO_METHOD)</div><div class="line">    soap_serve_request(service.soap);</div></div><!-- fragment --><p>where the <code>service</code> object is an instance of the application services generated by soapcpp2 <code>-j</code>.</p>
<p>Then compile the generated wsddClient.cpp file with the macro <code>-DSOAP_H_FILE=wsddH.h</code> to specify that <code>wsddH.h</code> should be used instead of `soapH.h.</p>
<p>To combine WS-Security with WS-Discovery, please see the next section.</p>
<h1><a class="anchor" id="wsdd_6"></a>
Miscellaneous</h1>
<p>You must generate client-side operations that the WSDD library expects to be linked with, by executing: </p><pre class="fragment">soapcpp2 -a -L -pwsdd -Iimport import/wsdd.h
</pre><p>Then compile the generated wsddClient.cpp file with the macro <code>-DSOAP_H_FILE=wsddH.h</code> to specify that <code>wsddH.h</code> should be used instead of `soapH.h.</p>
<p>If WS-Security is used with WS-Discovery, then create a file <code>imports.h</code> with the following two lines:</p>
<div class="fragment"><div class="line"><span class="comment">// file: imports.h</span></div><div class="line"><span class="preprocessor">#import &quot;<a class="code" href="wsdd_8h.html">wsdd.h</a>&quot;</span> <span class="comment">// or wsdd10.h, wsdd5.h</span></div><div class="line"><span class="preprocessor">#import &quot;wsse.h&quot;</span></div></div><!-- fragment --><p>Then execute: </p><pre class="fragment">soapcpp2 -a -L -pwsdd -Iimport imports.h
</pre><p>This generates wsddC.cpp and wsddClient.cpp, which should be compiled together with <a class="el" href="wsddapi_8c.html">plugin/wsddapi.c</a>, plugin/wsseapi.c, plugin/mecevp.c, and plugin/smdevp.c. All files should be compiled with <code>-DSOAP_H_FILE=wsddH.h</code>, i.e. macro <code>SOAP_H_FILE</code> set to <code>wsddH.h</code>. WS-Security requires OpenSSL and linkage with libssl and libcrypto.</p>
<p>For server-side projects, also compile and link the generated wsddServer.cpp code. You will also need to implement the <a class="el" href="wsdd_0.html#wsdd_2">WS-Discovery Event Handlers</a>.</p>
<p>Because WS-Addressing may relay faults to a FaultTo service, when implementing a service you will also have to define a SOAP Fault service operation to accept and handle these:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> <a class="code" href="wsa5_8h.html#af1f0af3d70354401b6969aa0b689a5dc">SOAP_ENV__Fault</a>(<span class="keyword">struct</span> soap *soap, <span class="keywordtype">char</span> *faultcode, <span class="keywordtype">char</span> *faultstring, <span class="keywordtype">char</span> *faultactor, <span class="keyword">struct</span> SOAP_ENV__Detail *detail, <span class="keyword">struct</span> SOAP_ENV__Code *SOAP_ENV__Code, <span class="keyword">struct</span> SOAP_ENV__Reason *SOAP_ENV__Reason, <span class="keywordtype">char</span> *SOAP_ENV__Node, <span class="keywordtype">char</span> *SOAP_ENV__Role, <span class="keyword">struct</span> SOAP_ENV__Detail *SOAP_ENV__Detail)</div><div class="line">{ </div><div class="line">  ... = faultcode; <span class="comment">// SOAP 1.1 fault code string (QName)</span></div><div class="line">  ... = faultstring; <span class="comment">// SOAP 1.1 fault string</span></div><div class="line">  ... = faultactor; <span class="comment">// SOAP 1.1 fault actor string</span></div><div class="line">  ... = detail; <span class="comment">// SOAP 1.1 fault detail struct</span></div><div class="line">  ... = SOAP_ENV__Code; <span class="comment">// SOAP 1.2 fault code struct</span></div><div class="line">  ... = SOAP_ENV__Reason; <span class="comment">// SOAP 1.2 reason struct</span></div><div class="line">  ... = SOAP_ENV__Node; <span class="comment">// SOAP 1.2 node string</span></div><div class="line">  ... = SOAP_ENV__Role; <span class="comment">// SOAP 1.2 role string</span></div><div class="line">  ... = SOAP_ENV__Detail; <span class="comment">// SOAP 1.2 detail struct</span></div><div class="line">  <span class="keywordflow">return</span> SOAP_OK;</div><div class="line">}</div></div><!-- fragment --><p>When implementing a WS-Discovery client and/or server without any other XML Web services, the above suffices to generate the required code. </p>
</div></div><!-- contents -->
<hr class="footer">
<address class="footer">
Copyright (C) 2020, Robert van Engelen, Genivia Inc., All Rights Reserved.
</address>
<address class="footer"><small>
Converted on Thu Nov 19 2020 12:38:04 by <a target="_blank" href="http://www.doxygen.org/index.html">Doxygen</a> 1.8.11</small></address>
<br>
<div style="height: 246px; background: #DBDBDB;">
</body>
</html>
